DeepWiki

08.b - GitHub-App-Configuration

Relevant source files

This document provides a comprehensive guide to creating and configuring the GitHub App required for godeep.wiki to authenticate with GitHub and access customer repositories. The GitHub App serves as the authentication mechanism that enables users to grant repository access during the payment-to-installation workflow.

For information about how the GitHub App integrates with the OAuth flow, see GitHub OAuth Initiation and OAuth Callback Handler. For details on environment variables required after app creation, see Environment Variables.

The GitHub App (godeepwiki-github-integration) provides the authentication infrastructure for the godeep.wiki system. It enables two distinct authentication patterns:

  1. User OAuth Authentication: Customers authenticate during the payment flow to grant repository access
  2. Installation Token Generation: The owner generates installation access tokens to clone customer repositories

The GitHub App is distinct from a GitHub OAuth App. While both support user authentication, a GitHub App provides installation-based access that allows the owner to access repositories on behalf of the installing user.

Sources: README.md L102-L156

.env.example L1-L15

app/api/auth/github/setup/route.ts L1-L67

GitHub Apps can be registered under either an organization or a personal account. The location determines the app's visibility and management structure.

Account TypeRegistration URLUse Case
Organizationhttps://github.com/organizations/YOUR_ORG/settings/apps/newMulti-user management, team access
Personalhttps://github.com/settings/apps/newSingle-owner management, simpler setup

For godeep.wiki, the app is registered under a personal account (Klaudioz) and managed at:

https://github.com/settings/apps/godeepwiki-github-integration

Sources: README.md L106-L108

The following table specifies the required basic configuration for the GitHub App:

SettingValuePurpose
GitHub App nameGoDeep Wiki Integration or godeepwiki-github-integrationUnique identifier for the app
DescriptionSee description template belowUser-facing explanation of app purpose
Homepage URLhttps://godeep.wikiApp landing page
Callback URLhttps://godeep.wiki/api/auth/github/callbackOAuth redirect endpoint
Setup URL (optional)https://godeep.wiki/api/auth/github/setupPost-installation configuration

GitHub provides a description field for users to understand the app's purpose. The recommended description emphasizes security best practices:

Allows users to share a repo to generate a deep documentation⚠️ Please select "Only select repositories" during installationfor security. Choose only the repo you want to document.

This description is stored in github-app-description.md L1-L47

with multiple length variants for character-limited fields.

Sources: README.md L112-L118

github-app-description.md L1-L47

.env.example L7

The GitHub App requires minimal read-only permissions to access repository contents and user metadata. This principle of least privilege minimizes security exposure.

PermissionAccess LevelPurpose
ContentsReadAccess repository files for documentation generation
MetadataReadAccess repository name, description, visibility status
PermissionAccess LevelPurpose
Email addressesReadIdentify customer for delivery correlation

The read-only permission model ensures that even if credentials are compromised, attackers cannot modify customer code. This aligns with the security principle documented in the high-level architecture diagrams.

Sources: README.md L130-L135

README.md L397-L402

The GitHub App must enable OAuth to support user authentication during the GitHub connection flow. Configure the following settings:

SettingValueRequired
Request user authorization (OAuth) during installation✅ EnabledYes
Callback URLhttps://godeep.wiki/api/auth/github/callbackYes
OAuth Scopesread:user user:emailYes
Enable Device Flow✅ Enabled (optional)No

The state parameter provides CSRF protection by ensuring the callback originated from the same session that initiated the OAuth flow. This is implemented in app/api/auth/github/route.ts

(state generation) and verified in app/api/auth/github/callback/route.ts

(state validation).

Sources: README.md L137-L140

app/api/auth/github/setup/route.ts L52-L62

While the system does not use GitHub App webhooks (it uses Stripe webhooks instead), the GitHub App configuration includes a webhook secret field that should be configured for future extensibility.

SettingEnvironment VariablePurpose
Webhook URLNot currently usedFuture event notifications
Webhook SecretGITHUB_WEBHOOK_SECRETSignature verification for webhook payloads

To generate a webhook secret:

# Generate a random secretopenssl rand -hex 32# Or use Node.jsnode -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Store the generated secret in both the GitHub App settings and the .env file as GITHUB_WEBHOOK_SECRET.

Sources: .env.example L6

During GitHub App installation, users are presented with two options for repository access:

  1. All repositories - Grants access to all current and future repositories
  2. Only select repositories - Grants access only to specified repositories

The system strongly recommends users select "Only select repositories" for security and privacy reasons. This recommendation is communicated in:

  • GitHub App description field
  • User-facing documentation
  • Installation prompts

The "Only select repositories" option is user-controlled, not enforced by the app developer. The GitHub App configuration cannot restrict this choice—it can only recommend best practices through documentation.

Sources: README.md L141-L145

github-app-description.md L8-L11

After creating the GitHub App, you must obtain five credentials and store them as environment variables.

GitHub App FieldEnvironment VariableFormatUsage
App IDGITHUB_APP_IDNumericJWT signing for installation tokens
Client IDGITHUB_CLIENT_IDIv1.xxxxxxxxxxxxxxxxOAuth flow initiation
Client SecretGITHUB_CLIENT_SECRETAlphanumeric stringToken exchange during OAuth callback
Private KeyGITHUB_PRIVATE_KEYPEM format RSA keyJWT signing for installation tokens
App SlugGITHUB_APP_SLUGLowercase with hyphensOAuth redirect URL construction

The private key is downloaded as a .pem file. To store it in the .env file:

# Read the private key filecat godeepwiki-github-integration.2024-01-01.private-key.pem# Copy the entire contents including header and footer# Example format:# -----BEGIN RSA PRIVATE KEY-----# MIIEpAIBAAKCAQEA...# ...multiple lines...# -----END RSA PRIVATE KEY-----# Store in .env with newlines preserved using \nGITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAK...\n-----END RSA PRIVATE KEY-----"

The private key is used by app/api/admin/generate-token/route.ts

to sign JWTs when generating installation access tokens.

Sources: README.md L146-L149

.env.example L1-L6

After obtaining credentials from the GitHub App settings, populate the following environment variables in your .env file:

# GitHub App IdentificationGITHUB_APP_SLUG=godeepwiki-github-integrationGITHUB_APP_ID=123456# OAuth Credentials (User Authentication)GITHUB_CLIENT_ID=Iv1.abcd1234567890abGITHUB_CLIENT_SECRET=abcd1234567890abcdef1234567890abcdef1234# Installation Token Credentials (Owner Authentication)GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAI...\n-----END RSA PRIVATE KEY-----"# Webhook Verification (Optional)GITHUB_WEBHOOK_SECRET=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Sources: .env.example L1-L6

README.md L76-L80

Post-Creation VerificationLink copied!

After configuring the GitHub App, verify the setup using the following checklist:

ComponentVerification MethodExpected Result
App SlugVisit https://github.com/apps/SLUGApp page loads without 404
OAuth CallbackTest OAuth flow from landing pageRedirects to /thank-you after authorization
PermissionsCheck app settingsContents: Read, Metadata: Read, Email: Read
Environment VariablesReview .env fileAll 5 GitHub variables populated
Private KeyTest token generationJWT signs successfully without errors

To verify the complete OAuth configuration:

  1. Navigate to the landing page at https://godeep.wiki
  2. Complete the $10 payment via Stripe
  3. Click "Connect GitHub Account" on the success page
  4. Verify redirect to https://github.com/apps/godeepwiki-github-integration/installations/new
  5. Select a test repository and approve permissions
  6. Verify redirect to callback URL /api/auth/github/callback
  7. Check Vercel logs for successful token exchange
  8. Verify redirect to /thank-you page

If any step fails, consult the Troubleshooting

section in the README.

Sources: README.md L314-L367

Once created, the GitHub App can be managed at:

ContextURL PatternExample
Organizationhttps://github.com/organizations/{ORG}/settings/apps/{APP_SLUG}https://github.com/organizations/godeep-wiki/settings/apps/godeepwiki-github-integration
Personalhttps://github.com/settings/apps/{APP_SLUG}https://github.com/settings/apps/godeepwiki-github-integration
Public Pagehttps://github.com/apps/{APP_SLUG}https://github.com/apps/godeepwiki-github-integration

GitHub provides an installations view showing all users who have installed the app. Access this at:

https://github.com/settings/apps/godeepwiki-github-integration/installations

This view displays:

  • User/organization name
  • Installation ID
  • Repository access scope (all vs. selected)
  • Installation date
  • Suspension status

The installation ID shown here corresponds to the installation_id captured during the OAuth callback and used for generating installation access tokens.

Sources: README.md L151-L156

All GitHub App credentials must be stored securely and never committed to version control:

  • Store in .env file (included in .gitignore)
  • Configure in Vercel environment variables for production
  • Never log credentials in application code
  • Rotate credentials if compromised

The system implements two token types with different lifespans:

Token TypeLifespanPurposeStorage
User OAuth Token24 hoursDashboard access for usersHTTP-only cookie
Installation Access Token1 hourRepository cloning by ownerTemporary (not stored)

The 1-hour installation token lifespan minimizes exposure if credentials are intercepted during the automation pipeline execution.

The GitHub App's read-only permissions ensure that even with valid credentials, the system cannot:

  • Modify repository contents
  • Delete files or repositories
  • Create branches or commits
  • Modify repository settings
  • Access GitHub Actions secrets

This defense-in-depth approach limits the blast radius of credential compromise.

Sources: README.md L394-L406

Diagram 3 from high-level architecture

404 Error: GitHub App Not Found

Symptom: Redirect to GitHub App installation returns 404

Cause: GITHUB_APP_SLUG doesn't match the actual app slug

Solution:

# Verify the slug matches the GitHub App URL# Correct: godeepwiki-github-integration# Incorrect: godeep-wiki or GoDeepWiki (case-sensitive)echo $GITHUB_APP_SLUG# Should output: godeepwiki-github-integration# The slug is part of the GitHub App URL:# https://github.com/apps/godeepwiki-github-integration#                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^#                        This is your GITHUB_APP_SLUG

Invalid Client Error

Symptom: OAuth flow fails with "Invalid client" error

Cause: Mismatch between GITHUB_CLIENT_ID and the app's actual client ID

Solution:

  1. Navigate to GitHub App settings
  2. Locate the "Client ID" field in the OAuth credentials section
  3. Copy the exact value (format: Iv1.xxxxxxxxxxxxxxxx)
  4. Update .env file
  5. Redeploy application

Private Key Format Error

Symptom: Token generation fails with "Invalid private key" or "PEM_read_bio" error

Cause: Private key not formatted correctly in environment variable

Solution:

# Correct format - newlines preserved with \nGITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"# Incorrect format - actual newlines break shell parsingGITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA...-----END RSA PRIVATE KEY-----"# In Vercel environment variables, use actual newlines in the text area# The platform handles escaping automatically

Sources: README.md L314-L367

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

Syntax error in text

mermaid version 11.4.1

08.b - GitHub-App-Configuration | DeepWiki | godeep.wiki